    /*
     * Safe extension of the Array class. Existing methods
     */
    
    use: 'ie.ondevice.objectkit.core';
    
    Array.implement.preventOverride= true;
    Array.implement
    (
        {
            /**
             * Determine the first most index of a value contained in an array.
             * The method returns a value of -1 if the array does not contain
             * the value.
             * 
             * @param {Object} value       Any value.
             * @return {Number}            The first index of the value, or -1.
             */
            indexOf: function (value) 
            {
                for (var i= 0, n= this.length; i<n; i++) 
                {
                    if (value === this[i])
                        return i;
                }
                
                return -1;
            }
            
            /**
             * Determine the last index of a value contained in an array. The 
             * method returns a value of -1 if the array does not contain the
             * value.
             * 
             * @param {Object} value        Any value.
             * @return {Boolean}            The last index of the value or -1.
             */
        ,   lastIndexOf: function (value) 
            {
                var n= this.length;
                while (n--) 
                {
                    if (value === this[n])
                        return n;
                }
                
                return -1;
            }
            
            /**
             * Determine if an array contains a particular value or not.
             * @param {Object} value        Any value
             * @return {true}               True whether the array contains the value
             */
        ,   contains: function (value) 
            {
                return -1 < this.indexOf(value);
            }
            
            /**
             * Determine if an array has an index or not.
             * 
             * @example
             *     <code>
             *         <pre>
             *             
             *             var a= [1];
             *             
             *             alert(a.has(0)); // true
             *             alert(a.has(1)); // true
             *             
             *             a.clear();
             *             
             *             
             *             
             *         </pre>
             *     </code>
             * 
             * @return {Boolean}
             */
        ,   has: function (index) 
            {
                return !isNaN(index) && index.hasOwnProperty(index);
            }
            
            /**
             * Remove the first occurance of a value from an array. Note that 
             * the array may still contain the value under other indices. To 
             * remove all occurances of the value from the array, use #removeAll
             * 
             * @example
             *     <code>
             *         <pre>
             *         
             *             var a= [1, 2, 3];
             *             a.remove(1);
             *             alert(a) ; // [1, 3]
             *         </pre>
             *     </code>
             * 
             * @param {Object} value        The value to remove.
             * @return {void}
             */
        ,   remove: function (value) 
            {
                var index= this.indexOf(value);
                if (-1 !== index)
                    this.splice(index, 1);
            }
            
            
            /**
             * Remove all occurances of a value from an array.
             * 
             * @example
             *     <code>
             *         <pre>
             *         
             *             var a= [1, 1, 1, 2, 3];
             *             a.removeAll(1);
             *             alert(a) ; // [2, 3]
             *         </pre>
             *     </code>
             *     
             * @param {Object} value        The value to remove.
             * @return {void}
             */
        ,   removeAll: function (value) 
            {
                if (0 === this.length)
                    return;
                    
                var filtered= [];
                
                for (var i= 0, n= this.length; i < n; i++) 
                {
                    if (value !== this[i]) 
                        filtered.push(this[i])  
                }

                this.clear();
                this.splice.apply(this, [0, filtered.length, filtered]);
            }
            
            /**
             * Determine if an array is empty or not
             * 
             * @example [].isEmpty() ;// true
             * @example [1].isEmpty(); // true
             * @return {Boolean}
             */
        ,   isEmpty: function () 
            {
                return 0 === this.length;    
            }
            
            /**
             * Clear the array, returning all its removed items.
             * @example var a= [1]; a.clear(); a.isEmpty(); // true
             * @return {Array}
             */
        ,   clear: function () 
            {
                this.splice(0,this.length);
            }
        }
    );
